<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta name="robot" content="index,follow">
<title>Module cbf - Circular buffer module - Forth Foundation Library</title>
</head>
<body>
<h2>cbf - Circular buffer module</h2>
<h3>Module Description</h3>
<p>The cbf module implements a circular buffer with variable elements.
During adding of extra data, the buffer will be resized. The cbf-access!
word expects two execution tokens on the stack: store with stack effect:
i*x addr --  and fetch: addr -- i*x. Those two words are used to store
data in the buffer and fetch data from the buffer. Their behavior should
match the size of the elements in the buffer.
Important: the cbf-get and cbf-fetch copy data from the buffer to the
destination address. This is different from the linear buffer [lbf]
implementation: the lbf-get and lbf-fetch return addresses located
in the buffer.
</p>
<h3>Module Words</h3>
<dl>
</dl>
<h4>Circular Buffer Structure</h4>
<dl>
<dt><a name="word1"><b>cbf%</b>	( -- n )</dt>
<dd>Get the required space for a cbf variable</dd>
</dl>
<h4>Buffer creation, initialisation and destruction</h4>
<dl>
<dt><a name="word2"><b>cbf-init</b>	( +n1 +n2 cbf -- )</dt>
<dd>Initialise the buffer with element size n1 and initial length n2</dd>
<dt><a name="word3"><b>cbf-(free)</b>	( cbf -- )</dt>
<dd>Free the internal data from the heap</dd>
<dt><a name="word4"><b>cbf-create</b>	( +n1 +n2 "&lt;spaces&gt;name" -- ; -- cbf )</dt>
<dd>Create a circular buffer in the dictionary with element size n1 and initial length n2</dd>
<dt><a name="word5"><b>cbf-new</b>	( +n1 +n2 -- cbf )</dt>
<dd>Create a circular buffer with element size n1 and initial length n2 on the heap</dd>
<dt><a name="word6"><b>cbf-free</b>	( cbf -- )</dt>
<dd>Free the circular buffer from the heap</dd>
</dl>
<h4>Member words</h4>
<dl>
<dt><a name="word7"><b>cbf-length@</b>	( cbf -- u )</dt>
<dd>Get the number of elements in the buffer</dd>
<dt><a name="word8"><b>cbf-extra@</b>	( cbf -- u )</dt>
<dd>Get the number of extra elements allocated during resizing of the buffer</dd>
<dt><a name="word9"><b>cbf-extra!</b>	( u cbf -- )</dt>
<dd>Set the number of extra elements allocated during resizing of the buffer</dd>
<dt><a name="word10"><b>cbf-size!</b>	( +n cbf -- )</dt>
<dd>Insure the size of the buffer</dd>
<dt><a name="word11"><b>cbf+extra@</b>	( -- u )</dt>
<dd>Get the initial number of extra elements allocated during resizing of the buffer</dd>
<dt><a name="word12"><b>cbf+extra!</b>	( u -- )</dt>
<dd>Set the initial number of extra elements allocated during resizing of the buffer</dd>
<dt><a name="word13"><b>cbf-access@</b>	( cbf -- xt1 xt2 )</dt>
<dd>Get the store word xt1 and the fetch word xt2 for the buffer</dd>
<dt><a name="word14"><b>cbf-access!</b>	( xt1 xt2 cbf -- )</dt>
<dd>Set the store word xt1 and the fetch word x2 for the buffer</dd>
</dl>
<h4>Lifo words</h4>
<dl>
<dt><a name="word15"><b>cbf-set</b>	( addr u cbf -- )</dt>
<dd>Set u elements, starting from addr in the buffer, resize if necessary</dd>
<dt><a name="word16"><b>cbf-fetch</b>	( addr u1 cbf -- u2 )</dt>
<dd>Fetch maximum u1 elements from the buffer in addr, return the actual number of elements u2</dd>
<dt><a name="word17"><b>cbf-get</b>	( addr u1 cbf -- u2 )</dt>
<dd>Get maximum u1 elements from the buffer in addr, return the actual number of elements u2</dd>
<dt><a name="word18"><b>cbf-skip</b>	( +n1 cbf -- +n2 )</dt>
<dd>Skip maximum u1 elements from the buffer, return the actual skipped elements u2</dd>
<dt><a name="word19"><b>cbf-enqueue</b>	( i*x | addr cbf -- )</dt>
<dd>Enqueue one element in the buffer, optional using the store word</dd>
<dt><a name="word20"><b>cbf-dequeue</b>	( cbf -- i*x | addr true | false )</dt>
<dd>Dequeue one element from the buffer, optional using the fetch word</dd>
</dl>
<h4>Fifo words</h4>
<dl>
<dt><a name="word21"><b>cbf-tos</b>	( cbf -- i*x | addr true | false )</dt>
<dd>Fetch the top element, optional using the fetch word</dd>
<dt><a name="word22"><b>cbf-push</b>	( i*x | addr cbf -- )</dt>
<dd>Push one element in the buffer, optional using the store word</dd>
<dt><a name="word23"><b>cbf-pop</b>	( cbf -- i*x | addr true | false )</dt>
<dd>Pop one element from the buffer, optional using the fetch word</dd>
</dl>
<h4>Buffer words</h4>
<dl>
<dt><a name="word24"><b>cbf-clear</b>	( cbf -- )</dt>
<dd>Clear the buffer</dd>
</dl>
<h4>Inspection</h4>
<dl>
<dt><a name="word25"><b>cbf-dump</b>	( cbf -- )</dt>
<dd>Dump the circular buffer variable</dd>
</dl>
<h3>Examples</h3>
<pre>
include ffl/cbf.fs


\ Example 1: buffering characters strings


\ Create the circulair buffer in the dictionary with an initial size of 10 chars

1 chars 10 cbf-create char-buf


\ Put characters in the buffer

s" Hello" char-buf cbf-set

\ Get the length of the stored characters

.( Number characters in buffer:) char-buf cbf-length@ . cr

\ Put more characters in the buffer, resulting in a resize of the buffer

s" , a nice morning to you." char-buf cbf-set


\ Get characters from the buffer

.( Read the buffer:) pad 29 char-buf cbf-get pad swap type cr



\ Example 2: buffering compound data: pair of cells as element


\ Create the circulair buffer on the heap with an initial size of 3 elements

2 cells 3 cbf-new value xy-buf


\ Set the store and fetch words for the buffer

' 2! ' 2@ xy-buf cbf-access!


\ Use the buffer as fifo buffer, using the store and fetch words

1 2 xy-buf cbf-enqueue
3 4 xy-buf cbf-enqueue
5 6 xy-buf cbf-enqueue
7 8 xy-buf cbf-enqueue       \ Buffer is resized

\ Get the length of the stored elements in the buffer

.( Number elements in buffer:) xy-buf cbf-length@ . cr

\ Get first element from buffer

.( First pair in buffer:) xy-buf cbf-dequeue [IF]
  .  . cr
[ELSE]
  .(  nothing in buffer) cr
[THEN]


\ Use the buffer as lifo buffer, using the store and fetch words

\ Get last pair from buffer

.( Last pair in buffer:) xy-buf cbf-pop [IF]
  . . cr
[ELSE]
  .(  nothing in buffer) cr
[THEN]

\ Free the buffer from the heap

xy-buf cbf-free

\ ==============================================================================
</pre>
<hr>
<div align="center">generated 24-Jul-2010 by <b>ofcfrth-0.10.0</b></div>
</body>
</html>
